%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%							Nicolas Jean
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% TODO: translate or remove
%%%%%%%% pour générer le pdf %%%%%%%
% compiler une première fois le .tex
% generate bibliography
%bibtex "programmer's manual" % TODO: does not work !
% générer le glossaire :
% makeindex -s preetude.ist -o preetude.gls preetude.glo
% recompiler une ou deux fois le .tex
%%%%%%%%%%%%%%

\documentclass[a4paper,11pt]{article}
% fichier (./style.sty) contenant les styles (still!)
\usepackage{style}

% pour remettre à zéro le compteur des sections à chaque nouvelle partie
% ne pas mettre dans le fichier style sinon ça foire !!!
\usepackage{remreset} \makeatletter \@addtoreset{section}{part} \makeatother

% rajoute des infos (titre, auteur, mots-clefs) au pdf, voir le fichier style (still !)
\docpdf

% RMQ (romain) : il y a sûrement une manière plus jolie d'intégrer l'image (en dehors de la balise title)



% pour avoir le titre sur chaque page
% À remettre à chaque partie !
\markright{Nepomuk Foxtrot - Programmer's Manual} 



\title{Nepomuk Foxtrot\\Swing your data, add the Nepomuk functions to Firefox and Thunderbird.\\\\
Programmer's Manual}


\author{Nicolas \textsc{Jean}\\
\\
Superviser: Stéphane \textsc{Laurière}}


\date{\today}


%%%%%%% GLOSSAIRE %%%%%%%
\usepackage[style=altlist,toc=true, number=none]{glossary}
%\makeglossary
%\include{glossaire}

%%%%%%% DÉBUT DU DOCUMENT %%%%%%%

\begin{document}

%% surtout NE PAS passer de lignes entre les deux parbox, sinon la seconde sera dans un paragraphe en dessous (logique)
% Logo en haut à gauche
\parbox[l]{0.32\linewidth}{
 \includegraphics[width=3cm]{img/insa.png}
}
% Petit texte en haut à droite
\parbox[c]{0.64\linewidth}{
\begin{flushright}
\textbf{M}andriva
\\Year 2008 -- other?
\end{flushright}
}

% generates the title
\maketitle



%%%%%%% SOMMAIRE %%%%%%%

\newpage

\renewcommand{\contentsname}{Table of contents}
% generate table of contents
\tableofcontents

\newpage

%%%%%%% GLOSSARY %%%%%%%
% @author Nicolas

%\printglossary

\newpage

%%%%%%% INTRODUCTION %%%%%%%

% @author Nicolas
% The '*' character indicates this part will not be numbered in the TOC.
\part*{Introduction}
\markright{Nepomuk Foxtrot - Programmer's Manual}

% add the introduction to the TOC
\addcontentsline{toc}{part}{Introduction}

Nepomuk Foxtrot is an extension for Mozilla Firefox 3 and Mozilla Thunderbird, though at the time of writing this document a greater effort has been made on developping the Firefox part.
Its goal is to provide the Nepomuk semantic functionalities such as tagging, rating, commenting, relating the web pages you visit or the mails you send and receive.
When using this extension, the quoted functionalities will be available directly in Mozilla's browser and e-mail client.

This document is meant to give a Nepomuk Foxtrot (future) programmer the basis to understand how the project is built, how it works, and how it can be improved.
In this aim, we will talk about the way things are connected to each others.
For example, how the data is stored, how we communicate with the data manager, which languages are used and for what reason.

Please note that the descriptions in this document are the way the author sees things, in such a manner that you may not agree with some points.




\part{Languages and technologies}
\markright{Nepomuk Foxtrot - Programmer's Manual}

% add this part to the TOC
% \addcontentsline{toc}{part}{Languages and technologies}

On figure \ref{fig:ext_org} you can see a first shot of how our the different technologies communicate.

\Figure{h,t,b,p}{350pt}{img/technologies.png}{Technologies and languages.}{fig:ext_org}


\section{Graphical interface - XUL}
\label{section_xul}

XUL is a description language based on XML that has been written by Mozilla to describe the contents of a graphical interface.
We have thus used it to implement the pages through which the user manages his or her data.
You should get used to this language if you are going to modify the interface - and you probably are.

XUL offers, or is, a ready-and-easy-to-use framework for describing graphical pages.
Such easy that when writing \verb"<button label='Click me' onclick='myFunction();'>", you will have an automatically-dimensionned button labeled ''Click me'' that calls the Javascript myFunction method you have defined.
We have find that XUL really makes you save time, and since it is very well processed by Mozilla, all the extensions we know use it.

As we will tell in the section concerning the use of Python, sometimes using the XUL components (e.g. the XUL:button object, to which the <button> tag is linked) can get a little tricky.
Apart from that, you usually do not have many surprises using the XUL elements.


\section{Scripts and actions - Javascript}
\label{section_javascript}

Javascript is a scripting language, the most-used for writing Firefox or Thunderbird extension.
One reason is the historical one: Javascript used to be the only language that could be interfaced with XUL (Javascript methods can be called from XUL pages, as seen in section \ref{section_xul}).
As you can see on figure \ref{fig:ext_org}, the communication is said to be \emph{implicit XPCOM}, meaning you do not have to care about XPCOM here.
Indeed, you can just call Javascript methods from your XUL-written pages, as (once again) shown in section \ref{section_xul}.

But for a while now, other languages are becoming available to be directly interfaced with XUL pages.
Among them: the Python scripting language.
This is the one we have chosen, the reasons are explained in section \ref{section_python}.
One of the consequences is that we do not need Javascript any more...
Or do we!
Indeed, we still use Javascript for a event-watching purpose.
Because as shown in section \ref{section_python}, there are still some problems using Python directly.


\section{Scripts and actions - Python}
\label{section_python}

The choice to use Python comes from its wide recent spread, its flexibility, its ease of use, the large number of useful classes to deal with several issues.
Furthermore, it appeared a good choice since an extension for Python XPCOM has been developped\footnote{see web page https://www.mozdev.org/projects/overview/pyxpcomext/}, meaning we can call Python methods from XUL pages, which is very intuitive and practical.

Nevertheless, there seem to be some lacks in this extension, causing some method calls to be impossible, at least quite tricky.
For this reason, we have at this time kept a little of Javascript coding, mainly to watch after events and react to them (like page change, firefox tag adding).

The chosen solution is, while waiting for Javascript to disappear definitely, to create XPCOM components that wraps the Python scripts / classes.
Some Javascript code watch for these particular events create the necessary XPCOM object and call back the appropriate method of it.
This will be more detailed in section \ref{XPCOM_components}.


\section{Data management - Soprano}
\label{section_soprano}

Soprano is a framework that gives access to many data-manipulation methods on RDF databases.
Soprano is thus useful for any RDF data manipulation, such as querying, adding statements\footnote{the RDF data-storing unit}, deleting some.

Though Soprano is written in C++, it is reachable from any Python script because most of its objects and methods have been ''exported'' to DBus.
This basically means a really simple way to use it, see section \ref{section_dbus} for details.


\section{Communication - DBus}
\label{section_dbus}

DBus is a way of communicating and passing data between applications.
In Nepomuk Foxtrot it is used for communication between Soprano (see section \ref{section_soprano}) and our Python scripts / classes, because this is the way Soprano is accessible from outside the C++ world.

This means that an object currently registered on DBus, that a \verb"Soprano::Model" (the object through which we can manipulate the Nepomuk data), can be accessed via DBus, its methods be called, and the results of these calls be obtained directly.
To sum up, we see a \verb"Soprano::Model" object just as if we had instantiated it ourselves, and can access its methods just like if any other object of ours.


\section{Communication - XPCOM}
\label{section_xpcom}

XPCOM is meant to enable cross-language programming, meaning that you can use a Python object from a Javascript program, for example.
That is exactly the situation in which we use it.
As we have told in sections \ref{section_javascript} and \ref{section_python}, we keep Javascript for watching some events of Firefox, and call Python methods when they occur.
This is done by creating an XPCOM object and simply calling the wanted method of it.

As can be seen on figure \ref{fig:ext_org}, there also is an XPCOM communication between Firefox (XUL pages) and the scripting languages (Javascript, Python), but this is invisible for the user.
Indeed, the interface between the two is based on XPCOM, but the programmer do not have anthing to do with XPCOM at this level.





\part{Extension's organisation}
\markright{Nepomuk Foxtrot - Programmer's Manual}

There are several elements in Nepomuk Foxtrot that are different in nature.
\begin{itemize}
\item the XUL pages are the different parts of the graphical interface, they allow the user to do actions, e.g. tag, rate or relate ;
\item the ''Python classes'' are the engine of the application, they give the possibility to actually realize the user requests ;
\item the event watchers are Javascript pieces of code that watch for particular Firefox events, and call the appropriate method of an XPCOM components to react to these events.
\end{itemize}
We are going to see these three parts in detail, from the lower-level to the higher-level classes.


\section{Python classes}

On figure \ref{fig:python_classes} you can see a simple UML diagram showing how the Python classes are organised.

\Figure{h,t,b,p}{350pt}{img/python-classes.png}{Python classes UML diagram.}{fig:python_classes}

The Interface class is the one that communicates with Soprano through DBus.
The Nao, Pimo and OntologyManager classes are specific to some topics, and use the Interface methods to interact with the RDF database.
TheNepomukWhisperer knows one instance of each of these classes, and is meant to be used as a link for the XUL pages (see section \ref{section_xulpages}) to have access to the engine, the Python classes.


\subsection{Interface \emph{or} ''how to manage all this RDF stuff''}

The Interface class is defined in the python\_interface\_to\_soprano.py file.
Its first goal is to provide methods to work with statements, e.g. creating, adding and deleting statements from the considered \verb"Soprano::Model", querying the database to know what has already been stored in it.
To do this, it communicates directly with Soprano via the dbus module (packet called ''python-dbus'', that must be installed).
Most of the other Python classes (Nao, Pimo, OntologyManager) relies on the Interface object to achieve this kind of work.

It also gives access to several utilities like
\begin{itemize}
\item functional tools, i.e. getting / setting the image of a resource by a property ;
\item derivation tools, basically for testing if a class derives from another, a kind of inference on the database ;
\item retrieval of lists of particular objects like types of Nepomuk elements, Nepomuk elements themselves ;
\item the very important \verb"registerAndReify" method, which is described in section \ref{difficulties}. % TODO: change ref
\end{itemize}


\subsection{Nao \emph{or} ''how to tag, rate and comment things''}

The ontology called NAO\footnote{NAO: Nepomuk Annotation Ontology.} is meant to provide specific ways of annotating any Nepomuk resource.
These ways are mainly tagging, rating and commenting resources.
The Nao class thus defines methods to set and get tags for a given resource, a rating or comment (also known as ''description'') for it.

There is a very specific way to tag your resource, that you can find explained on the Nao page\cite{www_nao_tagging}.

Further programming for the Nao class could consider implementing the \verb"nao:prefSymbol", which allows to attach an image to a resource.
This could be a very visual means to annotate a resource (e.g. web page).


\subsection{Pimo \emph{or} ''how to set relations between any Nepomuk elements''}

The ontology called PIMO\footnote{PIMO: Personal Information Model Ontology.} provides numerous properties to relate any two Nepomuk resources.
The aim of the Pimo class is to have generic methods to work on any kind of relations.
It includes the following works:
\begin{itemize}
\item retrieve information about which properties are available to create new relations, on which types of resources they can be used (property's domain and range) ;
\item retrieve Nepomuk resources that can be used with a particular property ;
\item create user-defined relations, delete relations ;
\item relate (and ''unrelate'') two resources using a given property, of course.
\end{itemize}


\subsection{OntologyManager \emph{or} ''how to manage ontologies''}

The OntologyManager offers two possibilities: to load some ontologies in the database, and to get specific lists of ontologies.
This retrieval of ontologies lists is used in cooperation with the Priority and PriorityLevel classes.


\subsubsection{Priority \& PriorityLevel \emph{or} ''how to restrict a request's results''}

This two classes are used to defined a priority system for restricting SPARQL requests by ontologies.
A Priority object stores a sorted list of PriorityLevel objects, so that its knows what to return for a given integer (represnting a level of priority).
The PriorityLevel stores a method name, and when it is asked to return ontologies, it tries to execute an OntologyManager's method with that name.
This method of the OntologyManager object is supposed to return a set of ontologies.

In this manner, when the OntologyManager is asked to get the set of ontologies for a given level (let us say \verb"n"), it asks its own priority system (Priority object), which itself asks its \verb"n"th PriorityLevel object which method of the OntologyManager should be called.


\subsection{TheNepomukWhisperer \emph{or} ''how to concentrate powers''}

TheNepomukWhisperer is an object that simply store one instance of each interesting element to have access to all needed methods.
At this time, an instance of the Interface, Nao, Pimo and OntologyManager instances.
This way, the whole engine that makes Nepomuk Foxtrot work is accessible from one object.


\section{XUL pages}
\label{section_xulpages}

There are a few things to know about the XUL pages.
Each one has two or three files to describe it:
\begin{itemize}
\item the .xul page, a XUL-written (based on XML) file which describes the appearance of the page and the actions corresponding to user actions (e.g. click on a button) ;
\item the .py script, a Python file that defines the methods that are called by the XUL page, responding to particular XUL events ;
\item the .js script, which is sometimes presents to watch for some events and call appropriate Python scripts.
\end{itemize}


\subsection{XUL pages \emph{or} ''what else?''}

There is not much to say about the XUL pages, apart from their simplicity!
You will though notice something quite special in every XUL page: we do not load only the associated Python script, but also the \verb"xul_constants.py" script.

\subsubsection{XUL constants \emph{or} ''(some kind of) magic inside''}

The \verb"xul_constants.py" file is meant:
\begin{itemize}
\item to define constants that will be used by the so-called associated Python scripts, especially for path-resolving issues ;
\item to 
\end{itemize}


\subsection{Python scripts \emph{or} ''behind the XUL scenes''}

Each XUL page comes with an associated Python script (defining appropriate methods).
This association is declared using the \verb"<script>" tag.

It defines the methods that are called in the XUL event handlers like using \verb"onclick='method()'" in the \verb'<button>' tag.

These scripts have


\section{Event watchers \& XPCOM components}



\part{Important things and difficulties}
\label{difficulties}






\bibliography{references}

\end{document}
















